RequestFocus

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODArbitrator

RequestFocus
The RequestFocus method requests that the ownership of the specified focus be assigned to the specified frame.
ODBoolean RequestFocus (in ODTypeToken focus, 
                        in ODFrame requestingFrame);
focus
A tokenized string representing the focus type whose ownership is being requested, expressed as a 32-bit value.
requestingFrame
A reference to a frame requesting the focus.
return value
kODTrue if the frame obtained the focus, otherwise kODFalse.

DISCUSSION
The focus parameter must be the tokenized form of one of the focus constants (kODClipboardFocus, kODKeyFocus, kODMenuFocus, kODModalFocus, kODMouseFocus, kODScrollingFocus, or kODSelectionFocus) or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to one of these constants.
Your part calls this method to request a single focus for one of its frames; to request multiple foci, your part calls the arbitrator's RequestFocusSet method. The return value indicates whether the specified frame obtained ownership of the specified focus.
If the specified focus is nonexclusive, the specified frame is automatically granted ownership of the focus. If it is exclusive, the focus module calls the BeginRelinquishFocus method of the current owner's part to see if the current owner is willing to give it up.
If the request is granted, the new ownership relationship is stored in the relevant focus modules. If the request fails, the existing ownership relationships remain intact.
If the request is granted, the arbitrator contains a reference to the frame. Parts should relinquish the focus in the DisplayFrameClosed or DisplayFrameRemoved methods.

EXCEPTIONS

kODErrFocusNotRegistered
The specified focus is not registered.

SEE ALSO
The ODFocusType type (page 889).
The ODTypeToken type (page 877).
The ODArbitrator::RequestFocusSet method (page 55).
The ODPart::BeginRelinquishFocus method (page 482).
The ODSession::Tokenize method (page 622).
Listing 2-31 on page 88 in OpenDoc Cookbook.
"Requesting Foci" on page 208 in OpenDoc Programmer's Guide.
"Handling a Simple Modal Dialog Box" on page 233 in OpenDoc Programmer's Guide.
"Acquiring and Relinquishing the Clipboard Focus" on page 356 in OpenDoc Programmer's Guide.